---
title: 安装 Astro
sidebar:
  label: '安装'
description: '如何安装 Astro 并开始一个新项目。'
i18nReady: true
---
import { Tabs, TabItem, FileTree, CardGrid, LinkCard, Steps } from '@astrojs/starlight/components';
import PackageManagerTabs from '~/components/tabs/PackageManagerTabs.astro';
import ReadMore from '~/components/ReadMore.astro';

[`create astro` CLI 命令](#通过-cli-向导安装) 是从零开始创建一个新的 Astro 项目的最快方式。它将引导你完成设置新 Astro 项目的每一个步骤，并允许你从几个不同的官方起始模板中选择。

你还可以运行带有 `template` 标志的 CLI 命令，以使用任何现有主题或起始模板来开始你的项目。探索我们的 [主题和起始模板 showcase](https://astro.build/themes/)，你可以在其中浏览到博客、作品集、文档网站、落地页等主题！

如果想要手动安装 Astro，请查看我们的[逐步手动安装指南](#手动安装)。

:::tip[在线预览]
想在浏览器中尝试 Astro 吗？访问 [astro.new](https://astro.new/) 浏览我们的起始模板，并在不离开浏览器的情况下启动一个新的 Astro 项目。
:::

## 前提条件

- **Node.js** - `v18.20.8` 或 `v20.3.0`、`v22.0.0` 或更高版本。（`v19` 和 `v21` 均不支持。）
- **文本编辑器** - 我们推荐使用 [VS Code](https://code.visualstudio.com/) 并安装我们的 [官方 Astro 扩展](https://marketplace.visualstudio.com/items?itemName=astro-build.astro-vscode)。
- **终端** - Astro 通过其命令行界面（CLI）访问。

## 浏览器兼容性

Astro 使用 Vite 构建，Vite 默认针对支持现代 JavaScript 的浏览器。要阅读完整的参考，你可以 [在 Vite 中查看当前支持的浏览器版本列表](https://cn.vite.dev/guide/build#browser-compatibility)。

## 通过 CLI 向导安装

你可以在计算机上的任何地方运行 `create astro`，因此在开始之前无需创建一个新的空目录。如果你还没有为你的新项目准备一个空目录，向导将会自动为你创建一个。

<Steps>
1. 在你的终端运行以下命令以启动我们的安装向导：

    <PackageManagerTabs>
      <Fragment slot="npm">
      ```shell
      # 使用 npm 创建一个新项目
      npm create astro@latest
      ```
      </Fragment>
      <Fragment slot="pnpm">
      ```shell
      # 使用 pnpm 创建一个新项目
      pnpm create astro@latest
      ```
      </Fragment>
      <Fragment slot="yarn">
      ```shell
      # 使用 yarn 创建一个新项目
      yarn create astro
      ```
      </Fragment>
    </PackageManagerTabs>

    如果一切顺利，你将看到一个成功信息，随后是一些推荐的后续步骤。

2. 现在你的项目已经创建好了，你可以 `cd` 进入你的新项目目录开始使用 Astro。

3. 如果你在 CLI 向导中跳过了 "Install dependencies?"（安装依赖？） 步骤，那么在继续之前请确保安装你的依赖。

    <PackageManagerTabs>
      <Fragment slot="npm">
      ```shell
      npm install
      ```
      </Fragment>
      <Fragment slot="pnpm">
      ```shell
      pnpm install
      ```
      </Fragment>
      <Fragment slot="yarn">
      ```shell
      yarn install
      ```
      </Fragment>
    </PackageManagerTabs>

4. 现在你可以 [启动 Astro 开发服务器](/zh-cn/develop-and-build/#启动-astro-开发服务器) 并在构建时看到你的项目的实时预览！
</Steps>

## CLI 安装标志

你可以运行带有附加标志的 `create astro` 命令来自定义安装的过程（例如，对每次询问都统一回答“是”，跳过 Houston 动画）或你的新项目（例如，是否安装 git，添加集成）。

<ReadMore>请参阅 [所有可用的 `create astro` 命令标志](https://github.com/withastro/astro/blob/main/packages/create-astro/README.md)。</ReadMore>

### 添加集成

你可以通过向 `create astro` 命令传递 `--add` 参数，它会在开始一个新的 Astro 项目的同时，为其安装任何支持 `astro add` 命令的 [官方集成](/zh-cn/guides/integrations-guide/) 或社区集成。

在你的终端中运行以下命令，可以替换为任何支持 `astro add` 命令的集成：

<PackageManagerTabs>
  <Fragment slot="npm">
  ```shell
  # 创建一个带有 React 和 Partytown 的新项目
  npm create astro@latest -- --add react --add partytown
  ```
  </Fragment>
  <Fragment slot="pnpm">
  ```shell
  # 创建一个带有 React 和 Partytown 的新项目
  pnpm create astro@latest --add react --add partytown
  ```
  </Fragment>
  <Fragment slot="yarn">
  ```shell
  # 创建一个带有 React 和 Partytown 的新项目
  yarn create astro --add react --add partytown
  ```
  </Fragment>
</PackageManagerTabs>

### 使用主题或起始模板

你也可以通过向 `create astro` 命令传递 `--template` 参数，基于 [官方示例](https://github.com/withastro/astro/tree/main/examples) 或任何 GitHub 仓库的 `main` 分支开始一个新的 Astro 项目。

在你的终端中运行以下命令，可以替换为官方 Astro 起始模板的名称，或者是你想使用的主题的 GitHub 用户名和仓库：

<PackageManagerTabs>
  <Fragment slot="npm">
  ```shell
  # 使用官方示例创建一个新项目
  npm create astro@latest -- --template <example-name>

  # 基于 GitHub 仓库的 main 分支创建一个新项目
  npm create astro@latest -- --template <github-username>/<github-repo>
  ```
  </Fragment>
  <Fragment slot="pnpm">
  ```shell
  # 使用官方示例创建一个新项目
  pnpm create astro@latest --template <example-name>
      
  # 基于 GitHub 仓库的 main 分支创建一个新项目
  pnpm create astro@latest --template <github-username>/<github-repo>
  ```
  </Fragment>
  <Fragment slot="yarn">
  ```shell
  # 使用官方示例创建一个新项目
  yarn create astro --template <example-name>
      
  # 基于 GitHub 仓库的 main 分支创建一个新项目
  yarn create astro --template <github-username>/<github-repo>
  ```
  </Fragment>
</PackageManagerTabs>

默认情况下，此命令将使用模板仓库的 `main` 分支。如果要使用不同的分支名称，请在 `--template` 参数中指定：`<github-username>/<github-repo>#<branch>`。

## 手动安装

本指南将指导你手动安装和配置新的 Astro 项目。

如果你不想使用我们的自动 `create astro` CLI 工具，可以按照下面的指南自行设置你的项目。

<Steps>
1. 创建你的目录

    创建一个以你的项目命名的空目录，然后进入该目录。

    ```bash
    mkdir my-astro-project
    cd my-astro-project
    ```

    进入你的新目录后，创建你的项目 `package.json` 文件。这是你管理项目依赖项（包括 Astro）的方式。如果你不熟悉这种文件格式，请运行以下命令创建一个。

    <PackageManagerTabs>
      <Fragment slot="npm">
      ```shell
      npm init --yes
      ```
      </Fragment>
      <Fragment slot="pnpm">
      ```shell
      pnpm init 
      ```
      </Fragment>
      <Fragment slot="yarn">
      ```shell
      yarn init --yes
      ```
      </Fragment>
    </PackageManagerTabs>

2. 安装 Astro

    首先，在你的项目中安装 Astro 的依赖项。

    :::note[重要]
    Astro 必须安装在本地，不能全局安装。确保你没有运行 `npm install -g astro`、`pnpm add -g astro` 或 `yarn add global astro`。
    :::

    <PackageManagerTabs>
      <Fragment slot="npm">
      ```shell
      npm install astro
      ```
      </Fragment>
      <Fragment slot="pnpm">
      ```shell
      pnpm add astro
      ```
      </Fragment>
      <Fragment slot="yarn">
      ```shell
      yarn add astro
      ```
      </Fragment>
    </PackageManagerTabs>

    然后，用以下内容替换你的 `package.json` 中的任何占位符 "scripts" 部分：

    ```json title="package.json" del={3} ins={4-6}
    {
      "scripts": {
        "test": "echo \"Error: no test specified\" && exit 1",
        "dev": "astro dev",
        "build": "astro build",
        "preview": "astro preview"
      },
    }
    ```

    你将在本指南后面使用这些脚本来启动 Astro 并运行其不同的命令。

3. 创建你的第一个页面

    在你的文本编辑器中，在你的目录下的 `src/pages/index.astro` 创建一个新文件。这将是你项目中的第一个 Astro 页面。

    对于本指南，请将以下代码片段（包括 `---` 破折号）复制并粘贴到你的新文件中：

    ```astro title="src/pages/index.astro"
    ---
    // 欢迎使用 Astro！这些三破折号代码围栏之间的内容是你的 "component frontmatter"。它不会在浏览器中运行。
    console.log('这段代码在你的终端运行，而不是在浏览器中！');
    ---
    <!-- 下面是你的 "component template"。它只是 HTML，但加入了一些魔法，帮助你构建出色的模板。 -->
    <html>
      <body>
        <h1>Hello, World!</h1>
      </body>
    </html>
    <style>
      h1 {
        color: orange;
      }
    </style>
    ```

4. 创建你的第一个静态资源

    你还需要创建一个 `public/` 目录来存储你的静态资源。Astro 将始终在你的最终构建中包含这些资源，因此你可以安全地从你的组件模板中引用它们。

    在你的文本编辑器中，在你的目录下的 `public/robots.txt` 创建一个新文件。`robots.txt` 是大多数网站会包含的一个简单文件，用于告诉像 Google 这样的搜索机器人如何处理你的网站。

    对于本指南，请将以下代码片段复制并粘贴到你的新文件中：

    ```diff title="public/robots.txt"
    # 示例：允许所有机器人扫描并索引你的网站。
    # 完整语法：https://developers.google.com/search/docs/advanced/robots/create-robots-txt
    User-agent: *
    Allow: /
    ```

5. 创建 `astro.config.mjs`

    Astro 使用 `astro.config.mjs` 进行配置。如果你不需要配置 Astro，这个文件是可选的，但你现在可能希望创建它。

    在你项目的根目录下创建 `astro.config.mjs`，并将下面的代码复制到其中：

    ```js title="astro.config.mjs"
    import { defineConfig } from 'astro/config';

    // https://astro.build/config
    export default defineConfig({});
    ```

    如果你想在你的项目中包含 [UI 框架组件](/zh-cn/guides/framework-components/)，如 React、Svelte 等，或使用其他工具，如 MDX 或 Partytown，这里是你[手动导入和配置集成](/zh-cn/guides/integrations-guide/)的地方。

    <ReadMore>阅读 Astro 的 [API 配置参考](/zh-cn/reference/configuration-reference/) 以获取更多信息。</ReadMore>

6. 添加 TypeScript 支持

    TypeScript 使用 `tsconfig.json` 进行配置。即使你不编写 TypeScript 代码，这个文件也很重要，以便工具（如 Astro 和 VS Code）了解你的项目。某些功能（如 npm 包导入）在没有 `tsconfig.json` 文件的情况下在编辑器中不完全支持。

    如果你打算编写 TypeScript 代码，建议使用 Astro 的 `strict` 或 `strictest` 模板。你可以在 [astro/tsconfigs/](https://github.com/withastro/astro/blob/main/packages/astro/tsconfigs/) 查看并比较三种模板配置。

    在你项目的根目录下创建 `tsconfig.json`，并将下面的代码复制到其中。（你可以使用 `base`、`strict` 或 `strictest` 作为你的 TypeScript 模板）：

    ```json title="tsconfig.json" "base"
    {
      "extends": "astro/tsconfigs/base"
    }
    ```

    <ReadMore>阅读 Astro 的 [TypeScript 设置指南](/zh-cn/guides/typescript/#设置) 以获取更多信息。</ReadMore>

7. 接下来

    如果你已经按照上面的步骤操作，你的项目目录现在应该如下所示：

    <FileTree>
    - node_modules/
    - public/
      - robots.txt
    - src/
      - pages/
        - index.astro
    - astro.config.mjs
    - package-lock.json 或 `yarn.lock`、`pnpm-lock.yaml` 等。
    - package.json
    - tsconfig.json
    </FileTree>

8. 现在你可以[启动 Astro 开发服务器](/zh-cn/develop-and-build/#启动-astro-开发服务器) 并在构建项目的同时查看实时预览了！

</Steps>
